home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / efun / add_action < prev    next >
Text File  |  2001-07-16  |  6KB  |  125 lines
  1. SYNOPSIS
  2.         #include <commands.h>
  3.  
  4.         void add_action(string fun, string cmd)
  5.         void add_action(string fun, string cmd, int flag)
  6.         void add_action(string fun)        /* historical */
  7.  
  8. DESCRIPTION
  9.         Set up a local function fun to be called when user input
  10.         matches the command cmd. Functions called by a user command
  11.         will get the arguments as a string. It must then return 0 if
  12.         it was the wrong command, otherwise 1.
  13.         
  14.         If it was the wrong command, the parser will continue
  15.         searching for another command, until one returns 1 or give an
  16.         error message to the user.
  17.         
  18.         For example, there can be a wand and a rod. Both of these
  19.         objects define as command "wave". One of them will be randomly
  20.         called first, and it must look at the argument, and match
  21.         against "wand" or "rod" respectively.
  22.         
  23.         If second argument cmd is not given, it must be given by
  24.         add_(x)verb(). Support of add_(x)verb() is for historical reasons
  25.         only, and not available without USE_DEPRECATED..
  26.         
  27.         The function associated to a command will be called with a
  28.         string as argument which stands for the given words behind the
  29.         typed command. The verb entered can be retrieved using the
  30.         query_verb() efun and is always the first word in the input
  31.         line up to the first space.
  32.         
  33.         Always have add_action() called only from an init() routine.
  34.         The object defining these commands must be present to the
  35.         user, either being the user, being carried by the user,
  36.         being the room around the user, or being an object in the
  37.         same room as the user. If the player leaves this vicinity of the
  38.         object, the actions are automatically removed.
  39.  
  40.         Actions can also be removed on demand with the remove_actions() efun.
  41.         
  42.         If argument <flag> is AA_SHORT (1), then the arguments may
  43.         follow the verb without separating space. Any arguments after
  44.         the first space are passed as argument string.
  45.  
  46.         If argument <flag> is AA_NOSPACE (2), then again the arguments
  47.         may follow the verb without separating space. In contrast to
  48.         AA_SHORT, all characters following the verb are passed as
  49.         the argument string. However, note that the characters immediately
  50.         following the given verb are passed as argument AND as result
  51.         of query_verb().
  52.  
  53.         If argument <flag> is AA_IMM_ARGS (3), then again the arguments
  54.         may follow the verb without separating space. All characters following
  55.         the given verb are passed as argument, and only as argument.
  56.  
  57.         If argument <flag> is negative, the verb given by the player
  58.         has to match only the leading -<flag> characters of the verb <cmd>.
  59.  
  60.         Never use one of the functions 'create' 'reset' 'init' 'exit'
  61.         'heart_beat' etc as the first argument to add_action(). In
  62.         general, a function with a name defined in /doc/applied should
  63.         have the behaviour defined there.
  64.  
  65. EXAMPLES
  66.         add_action("GoInside", "enter");
  67.         
  68.           When typing "enter" the function GoInside() will be invoked.
  69.         
  70.         add_action("DisFunc", "dis", AA_SHORT);
  71.         
  72.           Whenever you type in a command which starts with "dis" the
  73.           function DisFunc() will be called. To get the real word which
  74.           was typed in (because until now you only know that it was a
  75.           command beginning with "dis") you have to call the efun
  76.           query_verb().
  77.  
  78.         add_action("DisFunc", "disconnect", AA_NOSPACE);
  79.  
  80.           The function DisFunc() will be called for all commands which
  81.           use "disconnect" or a shortened form like "di", "dis" or
  82.           "discon" as verb. The command 'disconnecting' will _not_
  83.           be recognized. To get the real word which was typed in
  84.           you have to call the efun query_verb().
  85.  
  86.  
  87.         add_action("...", "cmd");
  88.         add_action("...", "xcmd", AA_SHORT);
  89.         add_action("...", "scmd", AA_NOSPACE);
  90.         add_action("...", "icmd", AA_IMM_ARGS);
  91.  
  92.           When given the following commands, the driver will parse it
  93.           as described below. 'verb' is what query_verb() would return,
  94.           'arg' is what would be passed to the command function.
  95.  
  96.           "cmd"          -> verb "cmd",     arg 0
  97.           "cmd foo bar"  -> verb "cmd",     arg "foo bar"
  98.  
  99.           "xcmd"         -> verb "xcmd",    arg 0
  100.           "xcmd foo"     -> verb "xcmd",    arg "foo"
  101.           "xcmdfoo"      -> verb "xcmdfoo", arg 0
  102.           "xcmd foo bar" -> verb "xcmd",    arg "foo bar"
  103.           "xcmdfoo bar"  -> verb "xcmdfoo", arg "bar"
  104.  
  105.           "scmd"         -> verb "scmd",    arg 0
  106.           "scmd foo"     -> verb "scmd",    arg " foo"
  107.           "scmdfoo"      -> verb "scmdfoo", arg "foo"
  108.           "scmd foo bar" -> verb "scmd",    arg " foo bar"
  109.           "scmdfoo bar"  -> verb "scmdfoo", arg "foo bar"
  110.  
  111.           "icmd"         -> verb "icmd",    arg 0
  112.           "icmd foo"     -> verb "icmd",    arg " foo"
  113.           "icmdfoo"      -> verb "icmd",    arg "foo"
  114.           "icmd foo bar" -> verb "icmd",    arg " foo bar"
  115.           "icmdfoo bar"  -> verb "icmd",    arg "foo bar"
  116.  
  117.  
  118. HISTORY
  119.         The flag < 0 argument was supported since 3.2@127, but not
  120.         really implemented before LDMud 3.2.8.
  121.         LDMud 3.2.9 introduced the AA_IMM_ARGS flag.
  122.  
  123. SEE ALSO
  124.         query_verb(E), query_command(E), add_verb(E), add_xverb(E), init(A)
  125.